home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / vbhelp.exe / HELP.BAS < prev    next >
BASIC Source File  |  1992-08-19  |  28KB  |  706 lines
  1. ' ------------------------------------------------------------------------
  2. ' Visual Basic for MS-DOS Help Toolkit
  3. '
  4. ' The Help Toolkit (HELP.BAS, HELPF.FRM, and HELPUTIL.FRM)
  5. ' makes it easy to add a hypertext Help system to your
  6. ' applications.
  7. '
  8. ' To use the Help Toolkit in your programs, include
  9. ' HELP.BAS, HELPF.FRM, and HELPUTIL.FRM in your program or
  10. ' use the supplied library (HELP.LIB, HELPA.LIB - AltMath
  11. ' version) and Quick library (HELP.QLB) and call the
  12. ' appropriate routines to load and display your help topics.
  13. ' Forms and code modules that call Help routines
  14. ' must include HELP.BI ('$INCLUDE: 'HELP.BI').
  15. '
  16. ' Help files can be written in any ASCII text editor or
  17. ' in Visual Basic itself.  Refer to the sample Help file
  18. ' HELPDEMO.TXT as an example of the Help file format.
  19. ' HELPDEMO.TXT also contains full information on creating
  20. ' Help files and using the Help Toolkit to display and
  21. ' navigate them.
  22. '
  23. ' The Help ToolKit consists of the following routines:
  24. '     HelpRegister   - initializes the Help system and loads Help file
  25. '     HelpShowTopic  - displays specified Help topic
  26. '     HelpClose      - closes Help file
  27. '     HelpSetOptions - sets Help display options
  28. '     HelpSearch     - invokes Help Search dialog to enable topic search
  29. ' Detailed descriptions of these procedures are contained
  30. ' in the comment headers above each.
  31. '
  32. ' Copyright (C) 1982-1992 Microsoft Corporation
  33. '
  34. ' You have a royalty-free right to use, modify, reproduce
  35. ' and distribute the sample applications and toolkits provided with
  36. ' Visual Basic for MS-DOS (and/or any modified version)
  37. ' in any way you find useful, provided that you agree that
  38. ' Microsoft has no warranty, obligations or liability for
  39. ' any of the sample applications or toolkits.
  40. ' ------------------------------------------------------------------------
  41.  
  42. ' Include file containing procedure declarations.
  43. '$INCLUDE: 'HELP.BI'
  44.  
  45. '$FORM frmHelpUtils         ' Form for Search, History, and Change dialogs
  46. '$FORM frmHelpMain          ' Help window
  47.  
  48. TYPE IndexType              ' Used to index Help topics
  49.     StartFilePtr AS LONG    ' Position within the topic's file
  50.     NumLines AS INTEGER     ' Number of lines in the Help topic
  51. END TYPE
  52.  
  53. TYPE PointType
  54.     X AS INTEGER            ' Horizontal location
  55.     Y AS INTEGER            ' Vertical location
  56. END TYPE
  57.  
  58. ' Variables common to HELP.BAS, HELPF.FRM, and HELPUTIL.FRM.
  59. COMMON SHARED /HelpLib/ DialogBackcolor AS INTEGER ' Background color for Help dialog boxes (Search, Copy, History)
  60. COMMON SHARED /HelpLib/ DialogForecolor AS INTEGER ' Foreground color for Help dialog boxes (Search, Copy, History)
  61.  
  62. ' Variables common to HELP.BAS and HELPF.FRM.
  63. COMMON SHARED /HelpLib/ Topic() AS STRING       ' Lines of the current Help topic
  64. COMMON SHARED /HelpLib/ LeftChar AS INTEGER     ' Leftmost character of the Help topic given the horizonal scroll position
  65. COMMON SHARED /HelpLib/ StartLine AS INTEGER    ' Top line of the Help topic given the vertical scroll position
  66. COMMON SHARED /HelpLib/ MaxLineLen AS INTEGER   ' Longest line of the Help topic
  67. COMMON SHARED /HelpLib/ HelpIndexPtr() AS IndexType ' Table that stores data about each Help topic
  68. COMMON SHARED /HelpLib/ HelpIndexTopics() AS STRING ' Array of Help topic names.  Used with the HelpIndexPtr table.
  69. COMMON SHARED /HelpLib/ HelpFileNum AS INTEGER  ' Logical file number assigned to the Help file by HelpRegister
  70. COMMON SHARED /HelpLib/ HelpTopicStack()  AS STRING ' Array of the last 20 Help topics shown
  71. COMMON SHARED /HelpLib/ HelpTopicStackPtr  AS INTEGER ' Number of topics in the HelpTopicStack
  72. COMMON SHARED /HelpLib/ TopicFound AS STRING    ' The Help topic being shown
  73. COMMON SHARED /HelpLib/ MaxHistoryStack AS INTEGER ' Maximum allowed size of the HelpTopicStack.  HelpRegister sets to 20.
  74. COMMON SHARED /HelpLib/ UnloadOnClose AS INTEGER ' Flag that determines if closing the Help form terminates the Help system.
  75. COMMON SHARED /HelpLib/ KillHelp AS INTEGER     ' Flag that HelpClose sets to terminate the Help form
  76. COMMON SHARED /HelpLib/ CursorPos AS PointType  ' Position of the currently selected Help link within a topic
  77. COMMON SHARED /HelpLib/ ButtonBarHeight AS INTEGER ' Number of lines to reserve at the top of the form for the button bar.  0 or 3.
  78. COMMON SHARED /HelpLib/ CloseOnEscape AS INTEGER ' If TRUE, pressing ESC will close the Help window
  79.  
  80. DEFINT A-Z
  81.  
  82. CONST FALSE = 0
  83. CONST TRUE = NOT FALSE
  84. CONST TabSpaces = 4                 ' Number of spaces that a TAB represents
  85.  
  86. DIM SHARED SelectedTopicColor AS INTEGER ' The foreground color of Help links
  87. DIM SHARED SpaceString AS STRING    ' A string of blank spaces used by the HelpPrintText procedure
  88. DIM SHARED HelpFileName AS STRING   ' Help file name.
  89.  
  90.  
  91. '----------------------------------------------------
  92. ' Sample usage of the Help Toolkit. This code is
  93. ' only executed if HELP.BAS is the start-up file.
  94. ' Parameter information for each Help procedure is
  95. ' contained in the header comments for the procedure.
  96. '----------------------------------------------------
  97.  
  98. ' Set the title bar background color to magenta (5),
  99. ' the screen background color to blue (1), and the
  100. ' access key color to red (4).
  101. screen.controlpanel(16) = 5
  102. screen.controlpanel(5) = 1
  103. screen.controlpanel(0) = 4
  104.  
  105. ' Initialize the Help system and load specified Help file.
  106. ' HelpLoaded% returns whether or not the Help file was
  107. ' loaded successfully.
  108. HelpRegister "HELPDEMO.TXT", HelpLoaded%
  109.  
  110. ' HelpLoaded% will be FALSE if HelpRegister fails.
  111. IF HelpLoaded% THEN
  112.     ' Set Help color and button display options.
  113.     ' Calls to this routine are optional as Help will
  114.     ' use its defaults if this call is ommitted.
  115.     HelpSetOptions 3, 0, 7, 0, 7, 11, 2
  116.  
  117.     ' Show the table of contents topic for the Help file.
  118.     ' Help will remain visible until window is closed
  119.     ' by the user.  Help topics can be changed by the user
  120.     ' once the Help window is made visible with the first
  121.     ' topic displayed.
  122.     HelpShowTopic "Contents"
  123. END IF
  124.  
  125. ' Help close and unload routine.
  126. '
  127. ' Closes help file and unloads help form.
  128. ' This routine should be called when the
  129. ' parent application terminates. If the parent
  130. ' routine has no END statement (e.g. it stops when
  131. ' the user closes the last form), the last Form_Unload
  132. ' must call this procedure.  Otherwise, the application
  133. ' will not end because frmHelpMain will still be loaded.
  134. '
  135. SUB HelpClose ()
  136.     KillHelp = TRUE
  137.     UNLOAD frmHelpMain
  138. END SUB
  139.  
  140. ' Internal routine that returns the greater of two integers.
  141. '
  142. FUNCTION HelpMax (int1 AS INTEGER, int2 AS INTEGER) AS INTEGER
  143.     IF int1 > int2 THEN
  144.         HelpMax = int1
  145.     ELSE
  146.         HelpMax = int2
  147.     END IF
  148. END FUNCTION
  149.  
  150. ' Internal routine that returns the lower of two integers.
  151. '
  152. FUNCTION HelpMin (int1 AS INTEGER, int2 AS INTEGER) AS INTEGER
  153.     IF int1 > int2 THEN
  154.         HelpMin = int2
  155.     ELSE
  156.         HelpMin = int1
  157.     END IF
  158. END FUNCTION
  159.  
  160. ' Help topic print routine.
  161. '
  162. ' Internal routine that prints Help topic text.
  163. ' Called when a topic is first shown and when
  164. ' the form is scrolled.
  165. '
  166. ' Parameters:
  167. '   TopLine   - The first element (line) of the topic
  168. '               array to be displayed.
  169. '   LeftPos   - The first character of each topic line
  170. '               to be displayed.
  171. '
  172. SUB HelpPrintText (TopLine AS INTEGER, LeftPos AS INTEGER)
  173.     MaxLines = UBOUND(Topic)    ' The number of lines in the Help topic.
  174.     IF TopLine > MaxLines THEN EXIT SUB
  175.     LastPrintedLine = TopLine + frmHelpMain.pctBackground.ScaleHeight ' The last line of the Help topic that will be printed.
  176.  
  177.     IF LastPrintedLine > MaxLines THEN
  178.         ' Ensures that the routine does not attempt to print more lines than the topic size
  179.         LastPrintedLine = MaxLines
  180.     END IF
  181.  
  182.     blanklines = frmHelpMain.pctBackground.ScaleHeight - (LastPrintedLine - TopLine - ButtonBarHeight) ' Number of blank lines on the form.
  183.     FormWidth = frmHelpMain.pctBackground.ScaleWidth ' Local variable copy of the form width.  Used to minimize property access.
  184.     frmHelpM